/*
 * Copyright 2011 Clean GWT
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
 * in compliance with the License. You may obtain a copy of the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software distributed under the License
 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 * or implied. See the License for the specific language governing permissions and limitations under
 * the License.
 */
package com.cleangwt.uibinder.client;

import com.cleangwt.json.client.SimpleObject;
import com.cleangwt.validation.client.Validator;
import com.google.gwt.event.logical.shared.ValueChangeEvent;

/**
 * Implement this interface and use GWT.create() to instantiate target class to generate
 * implementation method for retrieving and setting the form data. The validation binding is also
 * generated if any constraint annotation is tagged at the form fields. See
 * {@link com.cleangwt.validation.client.constraints.Constraint} and it's tagged annotations.
 * 
 * @author Jess
 * @version 1.0
 * @since 1.0
 */
public interface RequiresFormRebind extends RequiresRebind {
  /**
   * Updates each editor with the given object.
   * 
   * @param client the client(editor owner) provides editors
   * @param value the object to edit or present
   */
  void setFormData(SimpleObject value);

  /**
   * Flushes value of each editor into the given initial object, if the initial value is null create
   * a new one.
   * 
   * @param client the client(editor owner) provides editors
   * @param value the initial value
   * @return the value retrieved from editor inputs
   */
  SimpleObject getFormData(SimpleObject value);

  /**
   * Adds constraints for the given validator. After this method, you may call the
   * {@link Validator#activate()} to register {@link ValueChangeEvent} for each input. Or it will be
   * ensured once on the first call of {@link Validator#validate()}.
   * 
   * @param validator the validator
   * 
   * @see Validator#activate()
   * @see Validator#validate()
   */
  void addConstraints(Validator validator);
}